﻿/********************************************************
 *  ██████╗  ██████╗████████╗██╗
 * ██╔════╝ ██╔════╝╚══██╔══╝██║
 * ██║  ███╗██║        ██║   ██║
 * ██║   ██║██║        ██║   ██║
 * ╚██████╔╝╚██████╗   ██║   ███████╗
 *  ╚═════╝  ╚═════╝   ╚═╝   ╚══════╝
 * Geophysical Computational Tools & Library (GCTL)
 *
 * Copyright (c) 2023  Yi Zhang (yizhang-geo@zju.edu.cn)
 *
 * GCTL is distributed under a dual licensing scheme. You can redistribute 
 * it and/or modify it under the terms of the GNU Lesser General Public 
 * License as published by the Free Software Foundation, either version 2 
 * of the License, or (at your option) any later version. You should have 
 * received a copy of the GNU Lesser General Public License along with this 
 * program. If not, see <http://www.gnu.org/licenses/>.
 * 
 * If the terms and conditions of the LGPL v.2. would prevent you from using 
 * the GCTL, please consider the option to obtain a commercial license for a 
 * fee. These licenses are offered by the GCTL's original author. As a rule, 
 * licenses are provided "as-is", unlimited in time for a one time fee. Please 
 * send corresponding requests to: yizhang-geo@zju.edu.cn. Please do not forget 
 * to include some description of your company and the realm of its activities. 
 * Also add information on how to contact you by electronic and paper mail.
 ******************************************************/

#ifndef _GCTL_LEGENDRE_H
#define _GCTL_LEGENDRE_H

#include "../core.h"

namespace gctl
{
	/**
	 * @brief      伴随勒让德系数归一化类型
	 */
	enum legendre_norm_e
	{
		One, ///< 归一化总值为1
		Pi4, ///< 归一化总值为4*pi
	};

	/**
	 * @brief 利用递推公式计算[-1, 1]内不同阶数的勒让德多项式的值
	 * 
	 * @param order 阶数
	 * @param x 坐标位置
	 * @param derivative 计算相对于x的导数
	 * @return 多项式值
	 */
	double legendre_polynomials(size_t order, double x, bool derivative = false);

	/**
	 * @brief      计算向前列推的a系数，避免重复计算。
	 * 
	 * @note Fully normalized associated Legendre functions calculated by standard forward column methods
	 * Holmes, S. A., & Featherstone, W. E. (2002). A unified approach to the Clenshaw summation and the recursive computation of 
	 * very high degree and order normalized associated Legendre functions.
	 * Journal of Geodesy, 76(5), 279–299. https://doi.org/10.1007/s00190-002-0216-2
	 *
	 * @param[in]  max_order  最大的计算阶数
	 * @param      cs         返回的系数
	 */
	void get_a_nm_array(int max_order, array<array<double>> &cs);

	/**
	 * @brief      计算向前列推的b系数，避免重复计算。
	 * 
	 * @note Fully normalized associated Legendre functions calculated by standard forward column methods
	 * Holmes, S. A., & Featherstone, W. E. (2002). A unified approach to the Clenshaw summation and the recursive computation of 
	 * very high degree and order normalized associated Legendre functions.
	 * Journal of Geodesy, 76(5), 279–299. https://doi.org/10.1007/s00190-002-0216-2
	 *
	 * @param[in]  max_order  最大的计算阶数
	 * @param      cs         返回的系数
	 */
	void get_b_nm_array(int max_order, array<array<double>> &cs);

	/**
	 * @brief      计算标准前向列推法计算规格化的勒让德多项式
	 * 
	 * 二维数组中行数代表阶数列数为次数
	 * 
	 * @note Fully normalized associated Legendre functions calculated by standard forward column methods
	 * Holmes, S. A., & Featherstone, W. E. (2002). A unified approach to the Clenshaw summation and the recursive computation of 
	 * very high degree and order normalized associated Legendre functions.
	 * Journal of Geodesy, 76(5), 279–299. https://doi.org/10.1007/s00190-002-0216-2
	 *
	 * @param      nalf   返回的勒让德多项式系数，一个下半三角二维矩阵
	 * @param[in]  a_nm   A系数
	 * @param[in]  b_nm   B系数
	 * @param[in]  max_order  最大的计算阶数
	 * @param[in]  theta  计算点的纬度值（度）
	 * @param[in]  norm   系数的归一化总值大小
	 * @param[in]  derivative   计算相对于theta的导数
	 */
	void nalf_sfcm(array<array<double>> &nalf, const array<array<double>> &a_nm, 
		const array<array<double>> &b_nm, int max_order, double theta, 
		legendre_norm_e norm, bool derivative = false);
}

#endif //_GCTL_LEGENDRE_H